From b66c74767f8dc80249d251962a3636b56807aab3 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 28 Feb 2021 13:12:48 -0500 Subject: [PATCH] stylecontext: Convert docs --- gtk/gtkstylecontext.c | 239 +++++++++++++++++++++--------------------- 1 file changed, 122 insertions(+), 117 deletions(-) diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c index 71f4750252..b95af474d1 100644 --- a/gtk/gtkstylecontext.c +++ b/gtk/gtkstylecontext.c @@ -48,46 +48,41 @@ /** - * SECTION:gtkstylecontext - * @Short_description: Rendering UI elements - * @Title: GtkStyleContext + * GtkStyleContext: * - * #GtkStyleContext is an object that stores styling information affecting - * a widget. + * `GtkStyleContext` stores styling information affecting a widget. * - * In order to construct the final style information, #GtkStyleContext - * queries information from all attached #GtkStyleProviders. Style providers - * can be either attached explicitly to the context through - * gtk_style_context_add_provider(), or to the display through - * gtk_style_context_add_provider_for_display(). The resulting style is a - * combination of all providers’ information in priority order. + * In order to construct the final style information, `GtkStyleContext` + * queries information from all attached `GtkStyleProviders`. Style + * providers can be either attached explicitly to the context through + * [method@Gtk.StyleContext.add_provider], or to the display through + * [func@Gtk.StyleContext.add_provider_for_display]. The resulting + * style is a combination of all providers’ information in priority order. * - * For GTK widgets, any #GtkStyleContext returned by - * gtk_widget_get_style_context() will already have a #GdkDisplay and - * RTL/LTR information set. The style context will also be updated + * For GTK widgets, any `GtkStyleContext` returned by + * [method@Gtk.Widget.get_style_context] will already have a `GdkDisplay` + * and RTL/LTR information set. The style context will also be updated * automatically if any of these settings change on the widget. * - * # Style Classes # {#gtkstylecontext-classes} + * # Style Classes * * Widgets can add style classes to their context, which can be used to associate * different styles by class. The documentation for individual widgets lists * which style classes it uses itself, and which style classes may be added by * applications to affect their appearance. * - * GTK defines macros for a number of style classes. - * * # Custom styling in UI libraries and applications * - * If you are developing a library with custom #GtkWidgets that - * render differently than standard components, you may need to add a - * #GtkStyleProvider yourself with the %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK - * priority, either a #GtkCssProvider or a custom object implementing the - * #GtkStyleProvider interface. This way themes may still attempt - * to style your UI elements in a different way if needed so. + * If you are developing a library with custom widgets that render differently + * than standard components, you may need to add a `GtkStyleProvider` yourself + * with the %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK priority, either a + * `GtkCssProvider` or a custom object implementing the `GtkStyleProvider` + * interface. This way themes may still attempt to style your UI elements in + * a different way if needed so. * * If you are using custom styling on an applications, you probably want then * to make your style information prevail to the theme’s, so you must use - * a #GtkStyleProvider with the %GTK_STYLE_PROVIDER_PRIORITY_APPLICATION + * a `GtkStyleProvider` with the %GTK_STYLE_PROVIDER_PRIORITY_APPLICATION * priority, keep in mind that the user settings in * `XDG_CONFIG_HOME/gtk-4.0/gtk.css` will * still take precedence over your changes, as it uses the @@ -346,24 +341,25 @@ gtk_style_context_new_for_node (GtkCssNode *node) /** * gtk_style_context_add_provider: - * @context: a #GtkStyleContext - * @provider: a #GtkStyleProvider + * @context: a `GtkStyleContext` + * @provider: a `GtkStyleProvider` * @priority: the priority of the style provider. The lower - * it is, the earlier it will be used in the style - * construction. Typically this will be in the range - * between %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and - * %GTK_STYLE_PROVIDER_PRIORITY_USER + * it is, the earlier it will be used in the style construction. + * Typically this will be in the range between + * %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and + * %GTK_STYLE_PROVIDER_PRIORITY_USER * * Adds a style provider to @context, to be used in style construction. + * * Note that a style provider added by this function only affects * the style of the widget to which @context belongs. If you want * to affect the style of all widgets, use - * gtk_style_context_add_provider_for_display(). + * [func@Gtk.StyleContext.add_provider_for_display]. * - * Note: If both priorities are the same, a #GtkStyleProvider + * Note: If both priorities are the same, a `GtkStyleProvider` * added through this function takes precedence over another added - * through gtk_style_context_add_provider_for_display(). - **/ + * through [func@Gtk.StyleContext.add_provider_for_display]. + */ void gtk_style_context_add_provider (GtkStyleContext *context, GtkStyleProvider *provider, @@ -394,11 +390,11 @@ gtk_style_context_add_provider (GtkStyleContext *context, /** * gtk_style_context_remove_provider: - * @context: a #GtkStyleContext - * @provider: a #GtkStyleProvider + * @context: a `GtkStyleContext` + * @provider: a `GtkStyleProvider` * * Removes @provider from the style providers list in @context. - **/ + */ void gtk_style_context_remove_provider (GtkStyleContext *context, GtkStyleProvider *provider) @@ -416,23 +412,23 @@ gtk_style_context_remove_provider (GtkStyleContext *context, /** * gtk_style_context_add_provider_for_display: - * @display: a #GdkDisplay - * @provider: a #GtkStyleProvider + * @display: a `GdkDisplay` + * @provider: a `GtkStyleProvider` * @priority: the priority of the style provider. The lower - * it is, the earlier it will be used in the style - * construction. Typically this will be in the range - * between %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and - * %GTK_STYLE_PROVIDER_PRIORITY_USER + * it is, the earlier it will be used in the style construction. + * Typically this will be in the range between + * %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and + * %GTK_STYLE_PROVIDER_PRIORITY_USER * * Adds a global style provider to @display, which will be used - * in style construction for all #GtkStyleContexts under @display. + * in style construction for all `GtkStyleContexts` under @display. * - * GTK uses this to make styling information from #GtkSettings + * GTK uses this to make styling information from `GtkSettings` * available. * - * Note: If both priorities are the same, A #GtkStyleProvider - * added through gtk_style_context_add_provider() takes precedence - * over another added through this function. + * Note: If both priorities are the same, A `GtkStyleProvider` + * added through [method@Gtk.StyleContext.add_provider] takes + * precedence over another added through this function. **/ void gtk_style_context_add_provider_for_display (GdkDisplay *display, @@ -451,11 +447,11 @@ gtk_style_context_add_provider_for_display (GdkDisplay *display, /** * gtk_style_context_remove_provider_for_display: - * @display: a #GdkDisplay - * @provider: a #GtkStyleProvider + * @display: a `GdkDisplay` + * @provider: a `GtkStyleProvider` * * Removes @provider from the global style providers list in @display. - **/ + */ void gtk_style_context_remove_provider_for_display (GdkDisplay *display, GtkStyleProvider *provider) @@ -472,11 +468,11 @@ gtk_style_context_remove_provider_for_display (GdkDisplay *display, /** * gtk_style_context_set_state: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * @flags: state to represent * * Sets the state to be used for style matching. - **/ + */ void gtk_style_context_set_state (GtkStyleContext *context, GtkStateFlags flags) @@ -490,14 +486,15 @@ gtk_style_context_set_state (GtkStyleContext *context, /** * gtk_style_context_get_state: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * * Returns the state used for style matching. * - * This method should only be used to retrieve the #GtkStateFlags - * to pass to #GtkStyleContext methods, like gtk_style_context_get_padding(). - * If you need to retrieve the current state of a #GtkWidget, use - * gtk_widget_get_state_flags(). + * This method should only be used to retrieve the `GtkStateFlags` + * to pass to `GtkStyleContext` methods, like + * [method@Gtk.StyleContext.get_padding]. + * If you need to retrieve the current state of a `GtkWidget`, use + * [method@Gtk.Widget.get_state_flags]. * * Returns: the state flags **/ @@ -513,7 +510,7 @@ gtk_style_context_get_state (GtkStyleContext *context) /** * gtk_style_context_set_scale: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * @scale: scale * * Sets the scale to use when getting image assets for the style. @@ -545,7 +542,7 @@ gtk_style_context_set_scale (GtkStyleContext *context, /** * gtk_style_context_get_scale: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * * Returns the scale used for assets. * @@ -563,20 +560,23 @@ gtk_style_context_get_scale (GtkStyleContext *context) /* * gtk_style_context_save_to_node: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * @node: the node to save to * - * Saves the @context state, so temporary modifications done through - * gtk_style_context_add_class(), gtk_style_context_remove_class(), - * gtk_style_context_set_state(), etc. and rendering using - * gtk_render_background() or similar functions are done using the - * given @node. + * Saves the @context state to a node. * - * To undo, call gtk_style_context_restore(). + * This allows temporary modifications done through + * [method@Gtk.StyleContext.add_class], + * [method@Gtk.StyleContext.remove_class], + * [method@Gtk.StyleContext.set_state] etc. * - * The matching call to gtk_style_context_restore() must be done - * before GTK returns to the main loop. - **/ + * Rendering using [func@Gtk.render_background] or similar + * functions are done using the given @node. + * + * To undo, call [method@Gtk.StyleContext.restore]. + * The matching call to [method@Gtk.StyleContext.restore] + * must be done before GTK returns to the main loop. + */ void gtk_style_context_save_to_node (GtkStyleContext *context, GtkCssNode *node) @@ -592,15 +592,18 @@ gtk_style_context_save_to_node (GtkStyleContext *context, /** * gtk_style_context_save: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` + * + * Saves the @context state. * - * Saves the @context state, so temporary modifications done through - * gtk_style_context_add_class(), gtk_style_context_remove_class(), - * gtk_style_context_set_state(), etc. can quickly be reverted - * in one go through gtk_style_context_restore(). + * This allows temporary modifications done through + * [method@Gtk.StyleContext.add_class], + * [method@Gtk.StyleContext.remove_class], + * [method@Gtk.StyleContext.set_state] to be quickly + * reverted in one go through [method@Gtk.StyleContext.restore]. * - * The matching call to gtk_style_context_restore() must be done - * before GTK returns to the main loop. + * The matching call to [method@Gtk.StyleContext.restore] + * must be done before GTK returns to the main loop. **/ void gtk_style_context_save (GtkStyleContext *context) @@ -626,10 +629,11 @@ gtk_style_context_save (GtkStyleContext *context) /** * gtk_style_context_restore: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * * Restores @context state to a previous stage. - * See gtk_style_context_save(). + * + * See [method@Gtk.StyleContext.save]. **/ void gtk_style_context_restore (GtkStyleContext *context) @@ -649,25 +653,25 @@ gtk_style_context_restore (GtkStyleContext *context) /** * gtk_style_context_add_class: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * @class_name: class name to use in styling * * Adds a style class to @context, so later uses of the * style context will make use of this new class for styling. * - * In the CSS file format, a #GtkEntry defining a “search” + * In the CSS file format, a `GtkEntry` defining a “search” * class, would be matched by: * - * |[ + * ```css * entry.search { ... } - * ]| + * ``` * * While any widget defining a “search” class would be * matched by: - * |[ + * ```css * .search { ... } - * ]| - **/ + * ``` + */ void gtk_style_context_add_class (GtkStyleContext *context, const char *class_name) @@ -685,11 +689,11 @@ gtk_style_context_add_class (GtkStyleContext *context, /** * gtk_style_context_remove_class: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * @class_name: class name to remove * * Removes @class_name from @context. - **/ + */ void gtk_style_context_remove_class (GtkStyleContext *context, const char *class_name) @@ -709,7 +713,7 @@ gtk_style_context_remove_class (GtkStyleContext *context, /** * gtk_style_context_has_class: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * @class_name: a class name * * Returns %TRUE if @context currently has defined the @@ -745,18 +749,18 @@ _gtk_style_context_peek_property (GtkStyleContext *context, /** * gtk_style_context_set_display: - * @context: a #GtkStyleContext - * @display: a #GdkDisplay + * @context: a `GtkStyleContext` + * @display: a `GdkDisplay` * * Attaches @context to the given display. * - * The display is used to add style information from “global” style - * providers, such as the display's #GtkSettings instance. + * The display is used to add style information from “global” + * style providers, such as the display's `GtkSettings` instance. * - * If you are using a #GtkStyleContext returned from - * gtk_widget_get_style_context(), you do not need to + * If you are using a `GtkStyleContext` returned from + * [method@Gtk.Widget.get_style_context], you do not need to * call this yourself. - **/ + */ void gtk_style_context_set_display (GtkStyleContext *context, GdkDisplay *display) @@ -789,12 +793,12 @@ gtk_style_context_set_display (GtkStyleContext *context, /** * gtk_style_context_get_display: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * - * Returns the #GdkDisplay to which @context is attached. + * Returns the `GdkDisplay` to which @context is attached. * - * Returns: (transfer none): a #GdkDisplay. - **/ + * Returns: (transfer none): a `GdkDisplay`. + */ GdkDisplay * gtk_style_context_get_display (GtkStyleContext *context) { @@ -831,14 +835,14 @@ gtk_style_context_resolve_color (GtkStyleContext *context, /** * gtk_style_context_lookup_color: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * @color_name: color name to lookup * @color: (out): Return location for the looked up color * * Looks up and resolves a color name in the @context color map. * * Returns: %TRUE if @color_name was found and resolved, %FALSE otherwise - **/ + */ gboolean gtk_style_context_lookup_color (GtkStyleContext *context, const char *color_name, @@ -860,11 +864,11 @@ gtk_style_context_lookup_color (GtkStyleContext *context, /** * gtk_style_context_get_color: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * @color: (out): return value for the foreground color * * Gets the foreground color for a given state. - **/ + */ void gtk_style_context_get_color (GtkStyleContext *context, GdkRGBA *color) @@ -877,11 +881,11 @@ gtk_style_context_get_color (GtkStyleContext *context, /** * gtk_style_context_get_border: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * @border: (out): return value for the border settings * - * Gets the border for a given state as a #GtkBorder. - **/ + * Gets the border for a given state as a `GtkBorder`. + */ void gtk_style_context_get_border (GtkStyleContext *context, GtkBorder *border) @@ -901,11 +905,11 @@ gtk_style_context_get_border (GtkStyleContext *context, /** * gtk_style_context_get_padding: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * @padding: (out): return value for the padding settings * - * Gets the padding for a given state as a #GtkBorder. - **/ + * Gets the padding for a given state as a `GtkBorder`. + */ void gtk_style_context_get_padding (GtkStyleContext *context, GtkBorder *padding) @@ -925,11 +929,11 @@ gtk_style_context_get_padding (GtkStyleContext *context, /** * gtk_style_context_get_margin: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * @margin: (out): return value for the margin settings * - * Gets the margin for a given state as a #GtkBorder. - **/ + * Gets the margin for a given state as a `GtkBorder`. + */ void gtk_style_context_get_margin (GtkStyleContext *context, GtkBorder *margin) @@ -1116,15 +1120,15 @@ snapshot_insertion_cursor (GtkSnapshot *snapshot, /** * gtk_snapshot_render_insertion_cursor: * @snapshot: snapshot to render to - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * @x: X origin * @y: Y origin - * @layout: the #PangoLayout of the text + * @layout: the `PangoLayout` of the text * @index: the index in the #PangoLayout * @direction: the #PangoDirection of the text * * Draws a text caret using @snapshot at the specified index of @layout. - **/ + */ void gtk_snapshot_render_insertion_cursor (GtkSnapshot *snapshot, GtkStyleContext *context, @@ -1222,12 +1226,13 @@ gtk_snapshot_render_insertion_cursor (GtkSnapshot *snapshot, * what changes affect the styles * * Flags that modify the behavior of gtk_style_context_to_string(). + * * New values may be added to this enumeration. */ /** * gtk_style_context_to_string: - * @context: a #GtkStyleContext + * @context: a `GtkStyleContext` * @flags: Flags that determine what to print * * Converts the style context into a string representation. -- 2.30.2